All Composite Controls have a design-time representation (mandatory) that defines how the control is in design time. The run-time library complements the functionality built into the design-time library as it imparts a run-time behavior to the control. It is possible to avoid a run-time library by including the necessary run-time representation in the design-time library. However, in some cases, additional behavior is needed in the controls, which can be achieved only by a run-time library.

This topic describes the content that must be mandatorily defined for a run-time library while creating a control.

Attaching a Run-time Library

To associate a run-time library with a composite control, a mechanism is needed to load the library at the run time. This is done by defining a run-time representation for the control in thetoXFormMarkup()method.

The following sample code associates a control with a run-time library.

// this associates the control with a run-time behavior
this.m_xmlProperties.setAttribute("namespace", "mycontrols.runtimelibrary.Hyperlink");

In the example, the complete namespace of the run-time library is specified. The XForms run time understands the syntax and loads the appropriate type library, making it available in run time.

Types of Run time

You can implement the run-time type library for a composite control in two ways.

• Direct: A run-time type library can be directly loaded and attached to the composite control's run-time representation. The examples considered in the topics related to composite controls, such asHello World,Hyperlinkcontrols are such cases.
  
• Adapter: In this approach, a type library "plugs-in" the actual behavior into the composite control's run-time representation. The type can be in any form such as JavaScript and htm. The XForms run time recognizes only the adapter library, while the adapter takes care of communicating with both the XForms run time and the Run-time Library. This approach is especially useful in situations where a third-party library is used, which cannot be modified because of copyright issues.
  

Creating Run-time Libraries

Run-time type libraries have a standard interface. For information about the content and how it can be written, see Type Library.

Associating the Run-time Behavior

Follow the below steps to make a run-time library function on an XForm at run time:

1. Load the run-time library. This is done by the XForms run time that recognizes the namespace of the run-time library.
   
2. Once loaded, the libraries have various means of initializing itself and process data. The various possibilities of initialization are as follows.
   
   Attach To
   
   Some run-time libraries do not have a run-time GUI and only impart specific behavior to controls they are attached to. These cannot function independently and must be associated (attached) to certain controls. Once attached, the composite controls initialize on their own by attaching the necessary behavior to other controls.
   
   For example, theHyperlinkcontrol is invisible at run time and does not exist by itself. It needs to be attached to some control. The Attach To context-menu option must be enabled for such controls. The following sample code for theHyperlinkcontrol shows how the attached controls are initialized:
   

   Hyperlink.attachType = function(hyperlink)
   {
   	//make the control's background color orange here
   	if ( hyperlink.registeredControls )
   	{
   		var ctrls = hyperlink.registeredControls.split(";");
   		for (var i = 0; i < ctrls.length; i++)
   		{
   			var html = hyperlink.ownerDocument.getElementById(ctrls[i]);
   			html.style.backgroundColor = "orange";
   		}
   	}
   }

   In the above example,
   

• All initializations are done on theattachType()method of the run-time library. For details, see Type Library.
  
• Each control with the
  Attach To behavior will have an attributeregisteredControls, which is a list of (semi-colon separated) control IDs.
  
• TheHyperlinkcontrol will iterate through each control and initialize for each of them.
  
  The above code makes the background color of all attached controls turn orange.
  

Data Model

Some controls (such as Tree and XGrid) require data to operate upon. For such controls, a mandatory propertyModelneeds to be defined, which denotes the data model that supplies data to the control. The following sample code sets the data model for a Tree control.

Tree.attachType = function(tree)
{
	....
	....
	....
	if (tree.model)
	{
		if(tree.treeData) tree.treeData = null;
		var dataModel = tree.ownerDocument.parentWindow[tree.model];
		if (dataModel) dataModel.addListener("xforms-ondatacompleted", bindTreeData(tree, dataModel));
	}
}

function bindTreeData(tree, dataModel)
{
	return function(eventObject)
	{
		tree.setTreeData(dataModel.getData());
	}
}

In the above sample code:

• The Tree control looks for a property calledmodelon the control. This property is set during design time from the property sheet.
  
• The control listens to thexforms-ondatacompletedevent of the data model.
  
• On the event handler, it picks up the data and uses it for rendering purposes. In this case, it sets the data to the Tree control.
  
  There are innumerable possibilities of making a run-time library apart from the two most practiced approaches given here. You can set the necessary property in the run-time representation, collect it in the run-time library, and do the necessary initializations.
  

Accessing Application Object

To access the window application in which the control is loaded, use control.ownerDocument.defaultView.application.